﻿<!DOCTYPE html
  PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- saved from url=(0014)about:internet -->
<html xmlns:MSHelp="http://www.microsoft.com/MSHelp/" lang="en-us" xml:lang="en-us"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

<meta name="DC.Type" content="reference">
<meta name="DC.Title" content="task_arena Class">
<meta name="DC.subject" content="task_arena Class">
<meta name="keywords" content="task_arena Class">
<meta name="DC.Relation" scheme="URI" content="../../../reference/appendices/community_preview_features.htm">
<meta name="DC.Relation" scheme="URI" content="../../../reference/appendices/community_preview_features/task_arena_cls/task_scheduler_observer_ext_cls.htm">
<meta name="DC.Relation" scheme="URI" content="task_arena_cls/task_scheduler_observer_ext_cls.htm#task_scheduler_observer_ext_cls">
<meta name="DC.Relation" scheme="URI" content="../../task_groups.htm#taskgroups">
<meta name="DC.Relation" scheme="URI" content="../../task_scheduler/task_scheduler_init_cls.htm#task_scheduler_init_cls">
<meta name="DC.Format" content="XHTML">
<meta name="DC.Identifier" content="task_arena_cls">
<meta name="DC.Language" content="en-US">
<link rel="stylesheet" type="text/css" href="../../../intel_css_styles.css">
<title>task_arena Class</title>
<xml>
<MSHelp:Attr Name="DocSet" Value="Intel"></MSHelp:Attr>
<MSHelp:Attr Name="Locale" Value="kbEnglish"></MSHelp:Attr>
<MSHelp:Attr Name="TopicType" Value="kbReference"></MSHelp:Attr>
</xml>
</head>
<body id="task_arena_cls">
 <!-- ==============(Start:NavScript)================= -->
 <script src="..\..\..\NavScript.js" language="JavaScript1.2" type="text/javascript"></script>
 <script language="JavaScript1.2" type="text/javascript">WriteNavLink(3);</script>
 <!-- ==============(End:NavScript)================= -->
<a name="task_arena_cls"><!-- --></a>

 
  <h1 class="topictitle1">task_arena Class</h1>
 
   
  <div> 
	 <div class="section"><h2 class="sectiontitle">Summary</h2> 
		 
		<p> Explicit, user-managed task scheduler arena
		  representation. 
		</p>
 
	 </div>
 
	 <div class="section"><h2 class="sectiontitle">Syntax</h2> 
		 
		<pre>class task_arena;</pre> 
	 </div>
 
	 <div class="section"><h2 class="sectiontitle">Header</h2> 
		 
		<pre>#define TBB_PREVIEW_TASK_ARENA 1
#include “tbb/task_arena.h”</pre> 
	 </div>
 
	 <div class="section"><h2 class="sectiontitle">Description</h2> 
		 
		<p> A 
		  <samp class="codeph">task_arena</samp> class represents an internal task scheduler
		  object where a number of threads, limited by a maximal concurrency level, share
		  and execute tasks. 
		</p>
 
		<p> The concurrency level of a 
		  <samp class="codeph">task_arena</samp> is isolated and not affected by previous 
		  <samp class="codeph">task_scheduler_init</samp> specifications. 
		</p>
 
		<p> 
		  <div class="Note"><h3 class="NoteTipHead">
					Note</h3>The total number of threads created for a process is limited by
			 whichever is largest: the default number of threads for the machine or the
			 value specified by the first 
			 <samp class="codeph">task_scheduler_init</samp> object. Therefore the number of
			 threads assigned to a task_arena will never exceed that maximum value,
			 regardless of the concurrency level. 
		  </div> 
		</p>
 
		<p> 
		  <div class="Note"><h3 class="NoteTipHead">
					Note</h3>A task_arena may get fewer workers and never get the specified
			 number of threads, even if the specified concurrency level is lower than the
			 allowed maximum. 
		  </div> 
		</p>
 
		<p>A 
		  <samp class="codeph">task_arena</samp> object keeps a reference to its internal
		  representation, but does not fully control its lifetime. It cannot be destroyed
		  until it contains tasks and/or other worker threads reference it. 
		</p>
 
		<p> 
		  <div class="Note"><h3 class="NoteTipHead">
					Note</h3>The 
			 <samp class="codeph">task_arena</samp> constructors do not create the internal
			 arena objects. They are created lazily on first use, or by explicit call
			 to <samp class="codeph">task_arena::initialize</samp>.
		  </div> 
		</p>
 
		<p> Each user thread that explicitly or implicitly creates a 
		  <samp class="codeph">task_scheduler_init 
		  </samp>object contains an implicit internal task arena object. The
		  tasks spawned or enqueued in an arena cannot be executed in a different arena. 
		</p>
 
	 </div>
 
	 <div class="section"><h2 class="sectiontitle">Members</h2> 
		 
		<pre>namespace tbb {
class task_arena {
public:
    static const int automatic = <em>implementation-defined</em>;
    static int current_slot();
    task_arena(int max_concurrency = automatic, unsigned reserved_for_masters = 1);
    task_arena(const task_arena &amp;s);
    ~task_arena();
    void initialize();
    void initialize(int max_concurrency, unsigned reserved_for_masters = 1);
    void terminate();
    bool is_active();
    template&lt;typename F&gt; void enqueue( const F&amp; f );
    template&lt;typename F&gt; void enqueue( const F&amp; f, priority_t p );
    template&lt;typename F&gt; void execute(F&amp; f);
    template&lt;typename F&gt; void execute(const F&amp; f);
};
}</pre> 
	 </div>
 
	 <div class="section"><h2 class="sectiontitle">Examples</h2> 
		 
		<p>The following example runs two 
		  <samp class="codeph">parallel_for</samp> loops concurrently; one that is scalable
		  and one that is not. The non-scalable loop is limited to at most 2 threads so
		  that the majority of the threads can be saved for the more scalable loop.
		  It uses <samp class="codeph">task_group</samp> to wait for a specific subset of tasks.
		</p>
 
		<pre>tbb::task_scheduler_init def_init; // Use the default number of threads
tbb::task_arena limited(2);// no more than 2 threads in this arena
tbb::task_group tg;

limited.enqueue([&amp;]{ // use at most 2 threads
    tg.run([]{ // run in task group
        tbb::parallel_for(1, N, unscalable_work());
    });
}); 

// Run another job concurrently with the loop above
// It can use the default number of threads:
tbb::parallel_for(1, M, scalable_work());

// Put the wait for the task group inside execute()
// This will wait only for the tasks that are in
// this task group.
arena.execute([&amp;]{ tg.wait(); });</pre> 
	 </div>
 
	 <div class="section"> 
		
<div class="tablenoborder"><table cellpadding="4" summary="" frame="border" border="1" cellspacing="0" rules="all"><span class="tabledesc"> 
			 <p>The following table provides additional information on the members
				of this template class. 
			 </p>
 
		  </span><thead align="left"> 
				<tr> 
				  <th class="cellrowborder" valign="top" width="33.89830508474576%" id="d23587e161">Member 
				  </th>
 
				  <th class="cellrowborder" valign="top" width="66.10169491525423%" id="d23587e164">Description 
				  </th>
 
				</tr>
</thead>
 
			 <tbody> 
				<tr> 
				  <td class="cellrowborder" valign="top" width="33.89830508474576%" headers="d23587e161 "><samp class="codeph">task_arena(int max_concurrency = automatic,
						unsigned reserved_for_masters = 1) 
					 </samp> 
				  </td>
 
				  <td class="cellrowborder" valign="top" width="66.10169491525423%" headers="d23587e164 "> 
					 <p>Creates a <samp class="codeph">task_arena</samp>
						 with certain concurrency limit and some portion of it reserved 
						 for application threads.
					 </p>
 
					 <div class="Note"><h3 class="NoteTipHead">
					Note</h3>For the community preview implementation of <samp class="codeph">task_arena</samp>,
						 the only valid values for <samp class="codeph">reserved_for_masters</samp> are 0 and 1.
					 </div>
				  </td>
 
				</tr>
 
				<tr> 
				  <td class="cellrowborder" valign="top" width="33.89830508474576%" headers="d23587e161 "> 
					 <p><samp class="codeph">static const int
						  automatic</samp> 
					 </p>
 
				  </td>
 
				  <td class="cellrowborder" valign="top" width="66.10169491525423%" headers="d23587e164 "> 
					 <p>When passed as <samp class="codeph">max_concurrency</samp>
						to the above constructor, arena concurrency will be automatically set
						based on the hardware configuration. 
					 </p>
 
				  </td>
 
				</tr>
 
				<tr> 
				  <td class="cellrowborder" valign="top" width="33.89830508474576%" headers="d23587e161 "><samp class="codeph">task_arena(const
						task_arena&amp;)</samp> 
				  </td>
 
				  <td class="cellrowborder" valign="top" width="66.10169491525423%" headers="d23587e164 "> 
					 <p>Copies settings from another 
						<samp class="codeph">task_arena</samp> instance. 
					 </p>
 
				  </td>
 
				</tr>
 
				<tr> 
				  <td class="cellrowborder" valign="top" width="33.89830508474576%" headers="d23587e161 "><samp class="codeph">~task_arena()</samp> 
				  </td>
 
				  <td class="cellrowborder" valign="top" width="66.10169491525423%" headers="d23587e164 "> 
					 <p>Removes the reference to the internal
						arena representation, and destroys the <samp class="codeph">task_arena()</samp> instance.
						Not thread safe w.r.t. concurrent invocations of other methods. 
					 </p>
 
				  </td>
 
				</tr>
 
				<tr> 
				  <td class="cellrowborder" valign="top" width="33.89830508474576%" headers="d23587e161 ">
						<samp class="codeph">void initialize();</samp>
						<p></p>

						<p><samp class="codeph">void initialize(int max_concurrency,
							unsigned reserved_for_masters = 1);</samp>
						</p>

						<p></p>

				  </td>
 
				  <td class="cellrowborder" valign="top" width="66.10169491525423%" headers="d23587e164 ">Performs actual initialization of internal
					 arena representation. If arguments are specified, overrides previous concurrency settings.
					 Has no effect when called on already initialized arena.
					 <div class="Note"><h3 class="NoteTipHead">
					Note</h3>After the call to <samp class="codeph">initialize</samp>, the arena concurrency
						is fixed and cannot be changed.
					 </div> 
				  </td>
 
				</tr>
 
				<tr> 
				  <td class="cellrowborder" valign="top" width="33.89830508474576%" headers="d23587e161 "><samp class="codeph">void terminate()</samp>
				  </td>

				  <td class="cellrowborder" valign="top" width="66.10169491525423%" headers="d23587e164 ">Removes the reference to the internal arena representation
					 without destroying the task_arena object, which can then be re-used.
					 Not thread safe w.r.t. concurrent invocations of other methods.
				  </td>
 
				</tr>
 
				<tr> 
				  <td class="cellrowborder" valign="top" width="33.89830508474576%" headers="d23587e161 "><samp class="codeph">bool is_active()</samp>
				  </td>

				  <td class="cellrowborder" valign="top" width="66.10169491525423%" headers="d23587e164 ">Returns <samp class="codeph">true</samp> if the arena
					 has been initialized, <samp class="codeph">false</samp> otherwise.
				  </td>
 
				</tr>
 
				<tr> 
				  <td class="cellrowborder" valign="top" width="33.89830508474576%" headers="d23587e161 "><samp class="codeph">template&lt;F&gt; void
						enqueue(const F&amp;)</samp> 
				  </td>
 
				  <td class="cellrowborder" valign="top" width="66.10169491525423%" headers="d23587e164 "> 
					 <p>Enqueues a task into the arena to process specified functor
						and immediately returns. 
					 </p>
 
					 <div class="Note"><h3 class="NoteTipHead">
					Note</h3>Does not require the calling thread to join the arena;
						i.e. any number of threads outside of the arena can submit work to the arena
						without blocking. 
					 </div> 
					 <div class="Note"><h3 class="NoteTipHead">
					Caution</h3>There is no guarantee that tasks enqueued
						in an arena execute concurrently with respect to any other arena’s tasks. 
					 </div> 
				  </td>
 
				</tr>
 
				<tr> 
				  <td class="cellrowborder" valign="top" width="33.89830508474576%" headers="d23587e161 "><samp class="codeph">template&lt;F&gt; void
						enqueue(const F&amp;, priority_t)</samp> 
				  </td>
 
				  <td class="cellrowborder" valign="top" width="66.10169491525423%" headers="d23587e164 "> 
					 <p>Enqueues a task with specified task priority. Is similar to 
						<samp class="codeph">enqueue( const F&amp; )</samp> in all other ways. 
					 </p>
 
				  </td>
 
				</tr>
 
				<tr> 
				  <td class="cellrowborder" valign="top" width="33.89830508474576%" headers="d23587e161 "><samp class="codeph">template&lt;F&gt; void
						execute(F&amp;)</samp> 
					 <p> 
					 </p>
 
					 <p><samp class="codeph">template&lt;F&gt; void execute(const
						  F&amp;)</samp> 
					 </p>
 
					 <p> 
					 </p>
 
				  </td>
 
				  <td class="cellrowborder" valign="top" width="66.10169491525423%" headers="d23587e164 "> 
					 <p>If possible, the calling thread joins the arena and executes
						the specified functor, then leaves the arena and returns to previous task
						scheduler state. 
					 </p>
 
					 <p>If not possible to join, the call wraps the functor into a
						task, enqueues it in the arena and waits on an OS kernel synchronization object
						for task completion. 
					 </p>
 
					 <div class="Note"><h3 class="NoteTipHead">
					Note</h3>Any number of threads outside of the arena can submit
						work to the arena and be blocked. However, only the maximal number of threads
						specified for the arena can participate in executing tasks. 
					 </div> 
					 <div class="Note"><h3 class="NoteTipHead">
					Note</h3>May decrement the arena's demand for worker threads,
						causing a worker to leave, and thereby freeing a slot for the calling thread. 
					 </div> 
				  </td>
 
				</tr>
 
				<tr> 
				  <td class="cellrowborder" valign="top" width="33.89830508474576%" headers="d23587e161 "><samp class="codeph">static int current_slot()</samp> 
				  </td>
 
				  <td class="cellrowborder" valign="top" width="66.10169491525423%" headers="d23587e164 "> 
					 <p><strong>Returns:</strong> The index of the slot that the calling
						thread is assigned to in its current arena (if any).
						If the thread is not initialized with TBB, returns -1.
						This method can be used, for example, by a
						<samp class="codeph">task_scheduler_observer</samp> to pin threads
						entering an arena to specific hardware. 
					 </p>
 
				  </td>
 
				</tr>
 
			 </tbody>
 
		  </table>
</div>
 
	 </div>
 
  </div>
 
  
<div class="familylinks">
<div class="parentlink"><strong>Parent topic:</strong>&nbsp;<a href="../../../reference/appendices/community_preview_features.htm">Community Preview Features</a></div>
</div>
<div class="See Also">
<ul class="ullinks">
<li class="ulchildlink"><a href="../../../reference/appendices/community_preview_features/task_arena_cls/task_scheduler_observer_ext_cls.htm">task_scheduler_observer Class extensions</a><br>
</li>
</ul>

<h2>See Also</h2>
<div class="linklist">
<div><a href="task_arena_cls/task_scheduler_observer_ext_cls.htm#task_scheduler_observer_ext_cls">task_scheduler_observer Class extensions
		  </a></div>
<div><a href="../../task_groups.htm#taskgroups">Task Groups
		  </a></div>
<div><a href="../../task_scheduler/task_scheduler_init_cls.htm#task_scheduler_init_cls">task_scheduler_init Class
		  </a></div></div>
</div>

</body>
</html>
